When the GeMA simulator is initialized, its first action is to read the configuration file. Unless explicitly provided by the -c command line parameter, it looks for the file named defaultConfig.lua on the config directory on the same path as the GeMA executable.

Some of the options controlled by this file are:

Where GeMA will look for plugins;
Where GeMA will look for script libraries;
Whether the monitor server will be enabled or not and its configuration parameters;
Whether to log messages to the console and/or to a log file;
Where the default log file will be placed and its name;
Which kind of log messages should be printed and which should be hidden;
Which execution items should collect exectution time, memory and other run-time statistics

The configuation file can also be used to define default values for global simulation options and constants. This values can be overwritten by the simulation object.

For replacing a subset of the config options, instead of editing the global file, a better option is to create a user file that loads the basic default configration by calling dofile("$APP/config/defaultConfig.lua") and only replaces the needed configuration options. Then, when running GeMA, pass this new user config file with the -c option. The batch file used to run regression tests uses this strategy to load a personalized configuration file.

Some of the configuration options are file paths. For extra flexibility, those values can be created with the help of path macros that are expanded by GeMA.

The available configuration options are well explained in the default configuration file itself. Please refer to the actual file for an explanation of each option.

Enabling or disabling Log messages

In GeMA, all messages that get sent to the console and/or to the log file are created by logger objects. The logLevels table, located on the configuration file, can be used to control exactly which messages will be printed and wich will not.

Every message has a tag that identifies the logger that originated that message, together with its classification level. Logger names are GeMA component names, such as "gema.modelInfo", the logger that prints model information, or "gema.simRunner", the logger responsible for global messages while running the simulation. The classification level for each message is a label such as "error", "warning" or "info". A message tag is given by composing the component name with the classification label, like in "gema.simRunner.info". Refer to the configuration file for the complete list of logger names.

Available classification levels are:

trace: Trace information to help system debugging.
extinfo: Extended information.
info: Information regarding system evolution and configuration.
warning: A warning message reporting something strange but not necessarilly an error.
error: Reporting an error from which the system can continue (maybe not with its total capacity).
fatal: Reporting a fatal error. The system cannot continue.
time: Reporting timing information.
memory: Reporting memory information.

To learn the tag associated with every log message, just set logShowLoggerName = true in the configuration file and run a simulation. Each message will be prefixed with its tag.

The logLevels table defines which messages are enabled or disabled, and might look like:

logLevels = {
  {'*.time',             false},
  {'*.memory',           false},
  {'gema.sim.time',      true },
  {'gema.resultsInfo.*', false},
}

Each table line enables or disables the messages identified by a message tag, where the logger name or the classification level can be replaced by an * meaning all loggers or all classes. Rules are processed in order. If a later rule overlaps with a previous one, the later will prevail, which combined with * makes it easy to create general policies with exceptions. On the previous example, the first rule disables every time message, but the third rule explicitly enables time messages from the "gema.sim" logger, which means that only that logger will be able to show time messages.

When creating a customized logLevels table, keep in mind that the given set of rules is always processed after the following basic rules:

{'*',         true } -- Enables every message by default
{'qt.*',      false} -- Disables messages reported by the Qt libbrary
{'*.extinfo', false} -- Disables every message with extinfo classification
{'*.trace,    false} -- Disables every message with trace classification

Controlling the set of collected time, memory and additional attribute statistics

During model loading and execution, GeMA can collect several statistics on the execution time, memory and other relevant attributes. Those statistics are individually controlled by "progress items". Each progress item has an associated detail level that controls what will be collected and what will be printed (with the gema.runProgress logger).

The runProgressLevels table, located on the configuration file, can be used to control the desired "detail" level for each run progress item. Each entry is keyed by an item name and stores the desired detail level, a value between 0 and 4, as explained below. A typical table might look like:

runProgressLevels = {
  [":default"] = 1,
  ["fem.prepare.physics"] = 3,
  ["lisSolver"] = 3,
}

On this example, the default item detail level is set to 1, while the fem.prepare.physics and the lisSolver items are set to 3, a more detailed level. Item names are hierarchical, so in fem.prepare.physics we have a fem item with a child prepare and a grand-child physics. When setting a level for an item, it will propagate to all sub-items that are not present on the list. The special :default entry sets the default level for items that are not found on the table. It can be overridden by the -stats command line parameter.

Each existing orchestration process has an associated progress item named after the process plugin / call name, like io.prepareMeshFile or mm.meshMapping. An exception is the fem process that, due to its importance, handles statistics in a more detailed way. Also some other "global" items exist, like the modelLoad or the dump items. The documentation on the configuration file lists all the available additional, non-process, items.

As mentioned above, detail levels range from 0 to 4, with the following meanings:

0 : No tracking
1 : Normal statistics, Summary printing.
2 : Normal statistics, Detailed printing.
3 : Detailed statistics, Summary printing.
4 : Detailed statistics, Detailed printing.

The Normal or Detailed statistics define what will be collected. Not all items have a different detailed level. As a general rule, memory statistics are only gathered at the detailed level. The Summary or Detailed printing define what will be printed to the log. On summary, only global statistics will be printed at the simulation end. On Detailed, they will also be printed as each item is "executed".